
 Director
~~~~~~~~~~
Program		Director
Purpose		A Desktop Utility
Version		0.36, 6 September 2003
Author		The RISC OS Director developers,  2003


Note: Please read the !ReadMe file in this directory as it contains additional
information that has not been added to this file yet.


  Help file for Director
==========================

Director was originally written by Nick Craig-Wood. Many thanks go to him for
writing it. 


If you are reading this in !Edit then you might like to do Expand tabs on the
Edit menu to turn those [09]'s into something useful!

At the start of each section title is a  character (ALT-164 if your keyboard
doesn't have it) which can be used to search this file.


  Contents
============

 - Contents
 - License
 - Introduction
 - Internal changes
 - Motivation
 - Switching from Pinboard+ to Director
 - Switching from TreeMenu (or DirMenu) to Director
 - Oddities
 - Notes
 - Planned Extensions
 - Contacts
	

  License
===========

This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with
this program; if not, write to the Free Software Foundation, Inc., 59 Temple
Place - Suite 330, Boston, MA 02111-1307, USA


  Introduction
================

Director is a general purpose desktop tool. It allows you to customise your
desktop by creating menus of useful commands and icons to attach the menus
to. Any number of menus or icons can be created and attached in any order to
each other.

Director also allows an alternative and faster view onto files in the form of
directory menus and allows these menus to be attached to other menus also.

Director has some other useful features such as remembering the most recently
used files, the ability to add key strokes into the keyboard buffer and the
ability to produce directory menus over drive icons.

Director is fully customisable by the user, and can do many or all of the
functions of Pinboard+, TreeMenu (AKA DirMenu), Filer-, QuickDir, DeskUtils,
Memorizer, Menon and some of the functions of Filer+.

Director will only run on RISC OS 3.10 or later.


  Internal changes
====================

Since release 0.26 of Director there have been some major restructuring of
Director. The main goal of this restructuring is to make things a bit more
obvious as to where what type of files are within each directory to make
future expansion possible and make it easier on the user when a new release of
Director is made.

In achieving these goals user customisations have been moved out into to the
new Choices: section of the !Boot sequence. This allows user preferences to be
set on a pre-user basis (when supported by RISC OS). In order to maintain
compatibility with previous machines this is not mandatory and Director can
still handle user choices being inside itself.

So that user choices can override the default one set by Director the file
Choices:Director.Menus.AutoRun.!!SetVars (if it exists) is run just after the
Director module has been loaded. This allows the user to set any required
system variables. Director then loads its default configuration.Director
then loads the files from Choices:Director.Menus.AutoRun 


  Motivation
==============

Director was initially conceived as a replacement for Pinboard+ (by Thomas
Olsson). For those of you who don't know, Pinboard+ is a replacement
Pinboard module which allows user definable menus when clicking menu over the
backdrop.

The initial design of Director was in order to overcome the fact that
Pinboard+ needed a replacement pinboard module loaded (which did not work
fully under RISCOS 3.5) and the fact that there was no easy way of specifying
that you wanted the contents of a directory as a sub menu.

This then led on to the idea of incorporating the functions of TreeMenu (by
Julian Smith) into Director. This would then enable a directory tree listing
to be attached to a menu at any point.

These ideas led onto Director being more of a general purpose program,
merging several utilities into one compact package.

Memory usage was another of the main reasons for coding Director. Here's a
before and after on the memory front.

Before:

TreeMenu	65,536
Pinboard+	18,812 (module)
		43,324 (menu)
DeskUtils	32,768
Memorizer	14,128

Total		174,568 Bytes

After:

Program code	18,672
Workspace	 3,600
Heap		18,416 (119 blocks)

Total		40,688 Bytes

Thus giving a saving of 133,880 bytes or 130 kBytes!

Director will use a dynamic area if they are available. (This has several
advantages, the main one being less RMA fragmentation.)

Director also includes some ideas from Filer+ (by Jens H. Ovesen), Filer- (by
Franz Philipps), and Memorizer (by Ben Summers).

Director is written entirely in ObjAsm assembler for its compactness and ease
of making module tasks.

Although not all the ideas may have been my own, the coding is all mine
(including all the bugs)!


  Switching from Pinboard+ to Director
========================================

If you run the ExpandMenu program in the Utils directory you can convert your
old Pinboard+ menus into the new form expected by Director. This is a
textual form based on the Obey file and is a lot easier to maintain than a
graphical form. However if you prefer you can maintain your menus using the
Pinboard+ menu designer and ExpandMenu, however some of the new features of
Director will be unavailable to you.


  Switching from TreeMenu (or DirMenu) to Director
====================================================

Director has almost all the features of TreeMenu. By default it will enable
Directory menus over title bars of filer windows and other windows. You may
create icons as per TreeMenu also, see the section on Icons, and also the
example Menus.


  Oddities
============

If you are running RISCOS 3.5 or later and wonder why your Menu titles are
justified all wrong (my menu is called "Nick's Menu" and the Menu gets right
justified) it is because you have included a reserved key name as the last
word. This is RISCOS being helpful and lining up your key short cuts in
Menus. It doesn't line up a key short cut of M for instance and will attempt
to line up anything with the last word "Menu"! The solution is to put a hard
space before the "Menu" (hard space is ALT-SPACE).

If you put a -path <Director$CurrentDir> on your MenuMenu then beware,
looking at this Directory Menu will cause Director$CurrentDir and
Director$CurrentPath to change, so if you look at it again, you will be
looking up one level in the directory viewer. This can be fixed by using a
dynamic menu as your MenuMenu (the default menu can be configured to do this,
look at its start).

Director menus with sprites in are sometimes the wrong width under
RISCOS3.5. I think this is a bug in the OS. If you re-open the menu then
it may correct itself.

If you put Director in your boot sequence, make sure that you Filer_Run it
(not just Run) otherwise it won't start up properly.


  Notes
=========

Notes is designed to be a post-it note style extension to Director

The Notes system allows for multiple Notes files. This is so that a main entry
can have several sub-entries. The number of Notes files is only limited by your
imagination (and hard drive size!)

The default key combination to open the Notes menu is ^N (shift-ctrl-N), which
can be changed.

Please note that any Notes menu will not reflect the changes you make until is
closed and re-opened.

Please note that the Notes system can handle non-existent and empty files. It
cannot handle corrupt files, or files which do not fit the requirements.


 The Notes Menu
----------------

The Notes menu is generated from its associated Notes file. The default file
used is Director:Notes . 

All the Notes entries are listed in the order that they appear in the file, and
coloured with regards to their priority. 

New notes can be added from the 'New ...' submenu, or by editing the 'New ...'
text and pressing the Return key.


 The Notes Sub-Menu
--------------------

For each entry in the notes menu, there is a range of options available on its
submenu.

 - If the entry has an attached Notes file, then this file will be available
   from the 'Notes' sub-menu.
 - If the entry has an attached directory or file then the 'More' option will
   open a directory menu.
 - For all entries there is an edit option which opens the Edit menu.


 The Edit Menu
---------------

The Edit menu allows you to change all attributes of an entry.

 - The Name option allows you to change it's name.
 - The Notes option specifies a further Notes file.
   If at a later stage you which to rename the Notes file, all you have to do
   is edit this entry and the system will rename the file accordingly.
   If you want to remove the link to the Notes file, then set the option to
   'nothing'.
 - The More option points to a directory or file on your hard drive. For
   example, this can be useful for those who have 'Update website' under Notes.
   If you wish to remove the link to the specified directory or file then set
   the option to 'nothing'.
 - The Move option allows you to move the item up or down and to the top or
   bottom of the list.
 - The Priority option specifies the priority of the item. This can be on of
   Urgent, Important, Standard or Dull.
 - The Remove option removes the entry from the Notes file. Please be aware
   that if you remove the last item in a Notes file, the file will be deleted.


  Planned Extensions
======================

The list below is the various areas that Director can be/will be enhanced. It
isn't in any real order so if certain features are requested more than others
then they will be implemented sooner.

 - Display free space information for a drive under an icon
   This could also be expanded to show the free RAM under an icon.
 - File sorting algorithm(s). At the moment Director lists files case
   insensitively, but by ASCII code, along the lines of: AbC...xYz
   The options available are alphabetically like RISC OS 3 or alpha/num like
   RISC OS 4+. Sorting by size or date would require more work but could be
   done if it was wanted.
 - Get Director to canonicalise paths of any directories/files it opens as
   StrongED does. I.e. It opens SCSI::Gromit.$.Apps instead of Apps:
   An extension would be to make this feature (some how) configurable.
 - Improved support for windows. At the moment Director has good support for
   icons and menus, but very little for windows (I bet some of you didn't even
   know Director did do windows).`
 - To set up some sort of 'Run actions' menu. Which, depending on the
   filetype, offers to run the particular file with a particular application.
   This would need to be user configurable (everyone stores applications in
   different places, many applications can handle the same types, it cannot
   cover *every* application out there).
 - To be able to add options to a previously created menus.
 - To be able to define menu colours for permanent and temporary menus. Should
   be able to define the title bar colours as well.
 - Auto scrolling for menus.
 - Auto IconSprites or Filer_Boot applications. This can be: Never, When
   building permanent menus, When app. sprite doesn't exist and  All the time
   An extension would be to make this feature (some how) configurable.
 - To be able to run a command when Menu is pressed over a normal text item.
 - Make path options dragable
 - Make menu options clickable.
 - To change Director to create windows instead of menus. This would allow
   greater flexibility for displaying items, overcome the 8 menus limit in
   RISC OS and allow menus to persist if 'torn' off. However, this would come
   at the cost of increased complexity and would only be implemented if
   Director's support for windows was improved (see above).
 - A rewite of FindDrives to make it more modular and expandable.
 - To write a wimp Director Menu Editor program that would allow easy creation,
   modification and deletion of icons, menus and windows.
 - To make use of the programs in !Director.Apps (only supplied in the 'devel'
   archives). Some of them need their user interface modernizing whilst others
   are in need of a more substantial update. None of them were ever released
   with Director so they will all need testing. If you have ideas for menu
   incorporating them, please e-mail me.
 - A need to go through the various Director and desktop utilities that are out
   there and see if it's possible to incorporate them. I know that I have a
   folder containing possibly useful additions to Director which I will go
   through to see if they are good/interesting enough to be incorporated.
   If you have written one that you want to submit then please contact me. I
   will ensure that I have the authors permission before I incorporate
   anything.
 - Technical Documentation I have started a document in Ovation Pro, but it
   does need more work done on it.
 - To recreate/reverse engineer the assembled utilities that I haven't been
   able to find source code for. Alternatives may be used instead but that
   depends on licensing conditions. Note: this is essential if a 32-bit
   version of Director is to be produced. For your information the source code
   that I have managed to find is supplied in the devel archive.

Both Director and it's support library aren't 32-bit compatible. As the 
Director module is all ARM assembler it will need more than just a recompile 
to get it to work. All the associated utilities will also need going over to 
ensure that they will work without problems on the new system. This is likely 
to be a long and difficult task and so I am looking for volunteers to help me 
complete it. Please contact me if you think you could help. If you are 
interested then the main focus at the moment is to update AssLib - for the 
simple reason that that is the core of Director and also contains the most 
26-bit only code.


  Contacts
============

The current Director website is:
	http://director.sourceforge.net


There are two current mailing lists for Director and Director related
information.

The current developers can be contacted at:
	director-developers@lists.sourceforge.net
Please report any bugs in Director to this e-mail address.

A user mailing list is available at:
	director-users@lists.sourceforge.net

To subscribe to either of these two lists send an e-mail to:
	<list-name>-request@lists.sourceforge.net
with the body:
	subscribe
You will be sent a confirmation e-mail which you need to reply to in order to
subscribe to that list.


Any bug reports, ideas or donations gratefully received.




